<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Error system. -->

<div class='chapter'>4. </div><p class='cindent'><!-- error system -->
<p class='cindent'><!-- handling errors -->

The first section of this chapter explains how programs
can handle errors, by means of condition handlers.  It also explains how
a program can signal an error if it detects something it doesn't like.

The second explains how users can handle errors, by means of an interactive debugger;
that is, it explains how to recover if you do something wrong.
For a new user of the Lisp Machine, the second section is probably
much more useful; you may want to skip the first.

	The remaining sections describe some other debugging facilities.
Anyone who is going to be writing programs for the Lisp machine should
familiarize himself with these.

	The <font class="italic">trace</font> facility provides the ability to perform certain
actions at the time a function is called or at the time it returns.  The
actions may be simple typeout, or more sophisticated debugging functions.

	The <font class="italic">step</font> facility allows the evaluation of a form to be
intercepted at every step so that the user may examine just what is happening
throughout the execution of the form.

	The <font class="italic">MAR</font> facility provides the ability to cause a trap
on any memory reference to a word (or a set of words) in memory.  If
something is getting clobbered by agents unknown, this can help track
down the source of the clobberage.

<div class='section'>4.1 </div>
.subsection Conditions
<p class='cindent'><!-- conditions -->

	Programmers often want to control what action is taken by their
programs when errors or other exceptional situations occur.  Usually
different situations are handled in different ways, and in order to express
what kind of handling each situation should have, each situation
must have an associated name.  In Lisp Machine Lisp there is the
concept of a <font class="italic">condition</font>.  Every condition has a name, which is a
symbol.  When an unusual situation occurs, some condition is <font class="italic">signalled</font>, and a
<font class="italic">handler</font> for that condition is invoked.

	When a condition is signalled, the system (essentially) searches
up the stack of nested function invocations looking for a handler established
to handle that condition.
The handler is a function which gets called to deal with the condition.
The condition mechanism itself is
just a convenient way for finding an appropriate handler function given
the name of an exceptional situation.  On top of this is built the
error-condition system, which defines what arguments are passed to a handler
function and what is done with the values returned by a handler function.
Almost all current use of the condition mechanism is for errors, but the user
may find other uses for the underlying mechanism.

.page
<p class='cindent'><!-- signaller -->
<p class='cindent'><!-- signalling conditions -->
The search for an appropriate handler is done by the function <font class="lisp">signal</font>:

<div class='defun'><font class='exdent'><font class='funcname'>signal <font class='italic' color='purple'>condition-name &rest args</font></font></font><br>
<font class="lisp">signal</font> searches through all currently-established condition handlers,
starting with the most recent.  If it finds one that will handle
the condition <font class="italic">condition-name</font>, then it calls that handler with a first argument
of <font class="italic">condition-name</font>, and with <font class="italic">args</font> as the rest of the arguments.
If the first value returned by the handler is <font class="lisp">nil</font>, <font class="lisp">signal</font>
will continue searching for another handler; otherwise,
it will return the first two values returned by the handler.
If <font class="lisp">signal</font> doesn't find any handler that returns a non-<font class="lisp">nil</font>
value, it will return <font class="lisp">nil</font>.
</div>

<p class='cindent'><!-- condition handler -->
<p class='cindent'><!-- handling conditions -->

Condition handlers are established through the <font class="lisp">condition-bind</font> special form:

<div class="defspec"><font class='exdent'><font class='funcname'>condition-bind</font><font class="italic"> Special Form</font></font><br>
The <font class="lisp">condition-bind</font> special form is used for establishing handlers for conditions.
It looks like:
<pre class="lisp">
(condition-bind ((<font class="italic">cond-1</font> <font class="italic">hand-1</font>)
                 (<font class="italic">cond-2</font> <font class="italic">hand-2</font>)
                 ...)
  <font class="italic">body</font>)
</pre>
Each <font class="italic">cond-n</font> is either the name of a condition, or a list of names of conditions,
or <font class="lisp">nil</font>.  If it is <font class="lisp">nil</font>, a handler is set up for <font class="italic">all</font> conditions
(this does not mean that the handler really has to handle all
conditions, but it will be offered the chance to do so, and can return
<font class="lisp">nil</font> for conditions which it is not interested in).
Each <font class="italic">hand-n</font> is a form which is evaluated to produce a handler function.
The handlers are established sequentially such that the <font class="italic">cond-1</font>
handler would be looked at first.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(condition-bind ((:wrong-type-argument 'my-wta-handler)
                 ((lossage-1 lossage-2) lossage-handler))
    (princ "Hello there.")
    (= t 69))
</pre>
This first sets up the function <font class="lisp">my-wta-handler</font> to handle
the <font class="lisp">:wrong-type-argument</font> condition.  Then, it sets up the binding
of the symbol <font class="lisp">lossage-handler</font> to handle both the <font class="lisp">lossage-1</font>
and <font class="lisp">lossage-2</font> conditions.  With these handlers set up, it prints out a message and
then runs headlong into a wrong-type-argument error by calling the
function <font class="lisp">=</font> with an argument which is not a number.
The condition handler <font class="lisp">my-wta-handler</font> will be given a chance to
handle the error.  <font class="lisp">condition-bind</font>
makes use of ordinary variable binding, so that if the
<font class="lisp">condition-bind</font> form is thrown through, the handlers will be
disestablished.  This also means that condition handlers are established
only within the current stack-group.
</div>

.subsection Error Conditions

The use of the condition mechanism by the error system defines an
additional protocol for what arguments are passed to error-condition
handlers and what values they may return.

There are basically four possible responses to an error: <font class="italic">proceeding</font>,
<font class="italic">restarting</font>, <font class="italic">throwing</font>, or entering the <font class="italic">debugger</font>.
The default action, taken if no handler exists or deigns to handle
the error (returns non-<font class="lisp">nil</font>), is to enter the debugger.
A handler may give up on the execution that produced the error by
throwing (see <font class="lisp">*throw</font>, (*throw-fun)).  <font class="italic">Proceeding</font> means to
repair the error and continue execution.  The exact meaning of this
depends on the particular error, but it generally takes the form of
supplying a replacement for an unacceptable argument to some function,
and retrying the invocation of that function.  <font class="italic">Restarting</font> means
throwing to a special standard catch-tag, <font class="lisp">error-restart</font>.  Handlers
cause proceeding and restarting by returning certain special values,
described below.

	Each error condition is signalled with some parameters, the meanings of which
depend on the condition.  For example, the condition <font class="lisp">:unbound-variable</font>,
which means that something tried to find the value of a symbol which was unbound,
is signalled with one parameter, the unbound symbol.  It is always
all right to signal an error condition with extra parameters.

	An error condition handler is applied to several arguments.  The first
argument is the name of the condition that was signalled (a symbol).
This allows the same function to handle several different conditions,
which is useful if the handling of those conditions is very similar.
(The first argument is also the name of the condition for non-error conditions.)
The second argument is a <font class="lisp">format</font> control string (see the description
of <font class="lisp">format</font>, on (format-fun)).  The third argument
is <font class="lisp">t</font> if the error is <font class="italic">proceedable</font>; otherwise it is <font class="lisp">nil</font>.  The
fourth argument is <font class="lisp">t</font> if the error is <font class="italic">restartable</font>; otherwise it
is <font class="lisp">nil</font>.
The fifth argument is the name of the function that signalled the
error, or <font class="lisp">nil</font> if the signaller can't figure out the correct name to pass.
The rest of the arguments are the parameters with which the condition was signalled.
If the <font class="lisp">format</font> control string is used with these parameters,
a readable English message should be produced.  Since more
information than just the parameters might be needed to print a reasonable
message, the program signalling the condition is free to pass any extra
parameters it wants to, after the parameters which the condition is <font class="italic">defined</font>
to take.  This means that every handler must expect to be called
with an arbitrarily high number of arguments, so every handler should
have a <font class="lisp">&rest</font> argument (see (&rest)).

	An error condition handler may return any of several values.  If it
returns <font class="lisp">nil</font>, then it is stating that it does not wish to handle
the condition after all; the process of signalling will continue
looking for a prior handler (established farther down on the stack) as
if the handler which returned <font class="lisp">nil</font> had not existed at all.
(This is also true for non-error conditions.)
If the handler does wish to handle the condition, it can try to
proceed from the error if it is proceedable, or restart from it if it
is restartable, or it can throw to a catch tag.
Proceeding and restarting are done by returning two values.
To proceed, return the symbol <font class="lisp">return</font> as the first value, and the
value to be returned by the function <font class="lisp">cerror</font> as the second.
To restart, return the symbol <font class="lisp">error-restart</font> as the first value,
and the value to be thrown to the tag <font class="lisp">error-restart</font> as the second.
The condition handler must not return any other sort of values.  However,
it can legitimately throw to any tag instead of returning at all.
If a handler tries to proceed an unproceedable error or
restart an unrestartable one, an error is signalled.

	Note that if the handler returns <font class="lisp">nil</font>, it is not said to have
handled the error; rather, it has decided not to handle it, but to "continue to signal"
it so that someone else may handle it.  If an error is signalled
and none of the handlers for the condition decide to handle it, the
debugger is entered.

	Here is an example of an excessively simple handler for the <font class="lisp">:wrong-type-argument</font>
condition.
<pre class="lisp">
;;; This function handles the :wrong-type-argument condition,
;;; which takes two defined parameters: a symbol indicating
;;; the correct type, and the bad value.
(defun sample-wta-handler (condition control-string proceedable-flag
                           restartable-flag function
                           correct-type bad-value &rest rest)
 (prog ()
   (format error-output "~%There was an error in ~S~%" function)
   (lexpr-funcall (function format) 
		  control-string correct-type bad-value rest)
   (cond ((and proceedable-flag
	       (yes-or-no-p query-io "Do you want use nil instead?"))
	  (return 'return nil))
	 (t (return nil))))) ;don't handle
</pre>

If an error condition reaches the error handler, the control-C command may be
used to continue from it.  If the condition name has a <font class="lisp">si:eh-proceed</font> property,
that property is called as a function with two arguments, the stack-group and
the "ete" (an internal error-handler data structure).  Usually it will ignore
these arguments.  If this function returns, its value will be returned from the
<font class="lisp">ferror</font> or <font class="lisp">cerror</font> that signalled the condition.  If no such property
exists, the error-handler asks the user for a form, evaluates it, and causes
<font class="lisp">ferror</font> or <font class="lisp">cerror</font> to return that value.  Putting such a property on can
be used to change the prompt for this form, avoid asking the user, or change
things in more far-reaching ways.

.subsection Signalling Errors
<p class='cindent'><!-- signalling errors -->

	Some error conditions are signalled by the Lisp system when it detects
that something has gone wrong.  Lisp programs can also signal errors,
by using any of the functions <font class="lisp">ferror</font>, <font class="lisp">cerror</font>, or <font class="lisp">error</font>.
<font class="lisp">ferror</font> is the most commonly used of these.  <font class="lisp">cerror</font> is used
if the signaller of the error wishes to make the error be <font class="italic">proceedable</font>
or <font class="italic">restartable</font>, or both.  <font class="lisp">error</font> is provided for Maclisp compatibility.

	A <font class="lisp">ferror</font> or <font class="lisp">cerror</font> that doesn't have any particular
condition to signal should use <font class="lisp">nil</font> as the condition name.  The
only kind of handler that will be invoked by the signaller in this case is the kind
that handles <font class="italic">all</font> conditions, such as is set up by
<pre class="lisp">
(condition-bind ((nil <font class="italic">something</font>) ...) ...)
</pre>
In practice, the <font class="lisp">nil</font> condition is used a great deal.
<p class='cindent'><!-- nil, used as a condition name -->

<div class='defun'><font class='exdent'><font class='funcname'>ferror <font class='italic' color='purple'>condition-name control-string &rest params</font></font></font><br>
<font class="lisp">ferror</font> signals the condition <font class="italic">condition-name</font>.  Any
handler(s) invoked will be passed <font class="italic">condition-name</font> and <font class="italic">control-string</font>
as their first and second arguments, <font class="lisp">nil</font> and <font class="lisp">nil</font> for the third and fourth
arguments (i.e. the error will be neither proceedable nor restartable), the name
of the function that called <font class="lisp">ferror</font> for the fifth argument, and
<font class="italic">params</font> as the rest of their arguments.

Note that <font class="italic">condition-name</font> can be <font class="lisp">nil</font>, in which case no handler
will probably be found and the debugger will be entered.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(cond ((&gt; sz 60)
       (ferror nil
	       "The size, ~S, was greater then the maximum"
	       sz))
      (t (foo sz)))

(defun func (a b)
   (cond ((and (&gt; a 3) (not (symbolp b)))
          (ferror ':wrong-type-argument
                  "The name, ~1G~S, must be a symbol"
                  'symbolp
                  b))
         (t (func-internal a b))))
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>cerror <font class='italic' color='purple'>proceedable-flag restartable-flag condition-name control-string &rest params</font></font></font><br>
<font class="lisp">cerror</font> is just like <font class="lisp">ferror</font> (see (ferror-fun)) except that the handler
is passed <font class="italic">proceedable-flag</font> and <font class="italic">restartable-flag</font> as its
third and fourth arguments.  If <font class="lisp">cerror</font> is called with a
non-<font class="lisp">nil</font> <font class="italic">proceedable-flag</font>, the caller should be prepared
to accept the returned value of <font class="lisp">cerror</font> and use it to restart the
error.  Similarly, if he passes <font class="lisp">cerror</font> a non-<font class="lisp">nil</font> <font class="italic">restartable-flag</font>,
he should be sure that there is a <font class="lisp">*catch</font> above him for the tag <font class="lisp">error-restart</font>.

If <font class="italic">proceedable-flag</font> is <font class="lisp">t</font>, the user will be asked for a replacement
object which <font class="lisp">cerror</font> will return.  If <font class="italic">proceedable-flag</font> is not
<font class="lisp">t</font> and not <font class="lisp">nil</font>, <font class="lisp">cerror</font> will return without asking for
any particular object.

Note:  Many programs that want to signal restartable errors will want to use
the <font class="lisp">error-restart</font> special form; see (error-restart-fun).
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(do ()
    ((symbolp a))
  <font class="main">; Do this stuff until </font>a<font class="main"> becomes a symbol.</font>
  (setq a (cerror t nil ':wrong-type-argument
	     "The argument ~2G~A was ~1G~S, which is not ~3G~A"
	     'symbolp a 'a "a symbol")))
</pre>
Note: the form in this example is so useful that there is a standard
special form to do it, called <font class="lisp">check-arg</font> (see (check-arg-fun)).
</div>

<div class='defun'><font class='exdent'><font class='funcname'>error <font class='italic' color='purple'>message &optional object interrupt</font></font></font><br>
<font class="lisp">error</font> is provided for Maclisp compatibility.  In Maclisp,
the functionality of <font class="lisp">error</font> is, essentially, that <font class="italic">message</font>
gets printed, preceeded by <font class="italic">object</font> if present, and that
<font class="italic">interrupt</font>, if present, is a user interrupt channel to be invoked.

	In order to fit this definition into the Lisp Machine way of handling
errors, <font class="lisp">error</font> is defined to be:
<pre class="lisp">
(cerror (not (null <font class="italic">interrupt</font>))
        nil
        (or (get <font class="italic">interrupt</font> 'si:condition-name)
            <font class="italic">interrupt</font>)
        (cond ((missing <font class="italic">object</font>) ;<font class="main">If no <font class="lisp">object</font> given</font>
	       "~*~a")
              (t "~s ~a"))
        <font class="italic">object</font>
        <font class="italic">message</font>)
</pre>

	Here is what that means in English: first of all, the condition
to be signalled is <font class="lisp">nil</font> if <font class="italic">interrupt</font> is <font class="lisp">nil</font>.  If there is some
condition whose meaning is close to that of one of the Maclisp user interrupt
channels, the name of that channel has an <font class="lisp">si:condition-name</font> property,
and the value of that property is the name of the condition to signal.
Otherwise, <font class="italic">interrupt</font> is the name of the condition to signal; probably
there will be no handler and the debugger will be entered.

	If <font class="italic">interrupt</font> is specified, the error will be proceedable.
The error will not be restartable.  The <font class="lisp">format</font> control string
and the arguments are chosen so that the right error message gets printed,
and the handler is passed everything there is to pass.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='error-restart'>error-restart</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">error-restart</font> is useful for denoting a section of a program
that can be restarted if certain errors occur during its execution.
An <font class="lisp">error-restart</font> form looks like:
<pre class="lisp">
(error-restart
  <font class="italic">form-1</font>
  <font class="italic">form-2</font>
  <font class="italic">...</font>)
</pre>
The forms of the body are evaluated sequentially.  If an error occurs
within the evaluation of the body and is restarted (by a condition handler
or the debugger), the evaluation resumes at the beginning of the <font class="lisp">error-restart</font>'s
body.
<pre class="lisp">
<font class="main">Example:</font>
(error-restart
  (setq a (* b d))
  (cond ((&gt; a maxtemp)
         (cerror nil t 'overheat
		 "The frammistat will overheat by ~D. degrees!"
		 (- a maxtemp))))
  (setq q (cons a a)))
</pre>
If the <font class="lisp">cerror</font> happens, and the handler invoked (or the debugger) restarts
the error, then evaluation will continue with the <font class="lisp">(setq a (* b d))</font>,
and the condition <font class="lisp">(&gt; a maxtemp)</font> will get checked again.

<pre class="lisp">
<font class="main"><font class="lisp">error-restart</font> is implemented as a macro that expands into:</font>
(prog ()
 loop (*catch 'error-restart
              (return (progn
                         <font class="italic">form-1</font>
                         <font class="italic">form-2</font>
                         <font class="italic">...</font>)))
      (go loop))
</pre>
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='check-arg'>check-arg</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>The <font class="lisp">check-arg</font> form is useful for checking arguments
to make sure that they are valid.  A simple example is:
<pre class="lisp">
(check-arg foo stringp "a string")
</pre>
<font class="lisp">foo</font> is the name of an argument whose value should be a string.
<font class="lisp">stringp</font> is a predicate of one argument, which returns <font class="lisp">t</font>
if the argument is a string.  <font class="lisp">"a string"</font> is an English description
of the correct type for the variable.

The general form of <font class="lisp">check-arg</font> is
<pre class="lisp">
(check-arg <font class="italic">var-name</font>
           <font class="italic">predicate</font>
           <font class="italic">description</font>
	   <font class="italic">type-symbol</font>)
</pre>
<font class="italic">var-name</font> is the name of the variable
whose value is of the wrong type.  If the error is proceeded this variable will
be <font class="lisp">setq</font>'ed to a replacement value.  <font class="italic">predicate</font> is a test for whether the
variable is of the correct type.  It can be either a symbol whose function definition
takes one argument and returns non-<font class="lisp">nil</font> if the type is correct, or it can be a non-atomic
form which is evaluated to check the type, and presumably contains a reference to
the variable <font class="italic">var-name</font>.  <font class="italic">description</font> is a string which expresses <font class="italic">predicate</font>
in English, to be used in error messages.  <font class="italic">type-symbol</font> is a symbol which
is used by condition handlers to determine what type of argument was expected.
It may be omitted if it is to be the same as <font class="italic">predicate</font>, which must be a symbol
in that case.

The use of the <font class="italic">type-symbol</font> is not really well-defined yet, but the intention
is that if it is <font class="lisp">numberp</font> (for example), the
condition handlers can tell that a number was needed, and might try to
convert the actual supplied value to a number and proceed.

[We need to establish a conventional way of "registering" the
type-symbols to be used for various expected types.  It might as well
be in the form of a table right here.]

The <font class="italic">predicate</font> is usually a symbol such as <font class="lisp">fixp</font>, <font class="lisp">stringp</font>,
<font class="lisp">listp</font>, or <font class="lisp">closurep</font>, but when there isn't any convenient predefined
predicate, or when the condition is complex, it can be a form.  In this case
you should supply a <font class="italic">type-symbol</font> which encodes the type.  For example:
<pre class="lisp">
(check-arg a
           (and (numberp a) ( a 10.) (&gt; a 0.))
           "a number from one to ten"
           one-to-ten)
</pre>
If this error got to the debugger, the message
<pre class="lisp">
The argument a was 17, which is not a number from one to ten.
</pre>
would be printed.

In general, what constitutes a valid argument is specified in three
ways in a <font class="lisp">check-arg</font>.  <font class="italic">description</font> is human-understandable,
<font class="italic">type-symbol</font> is program-understandable, and <font class="italic">predicate</font> is
executable.  It is up to the user to ensure that these three
specifications agree.

<font class="lisp">check-arg</font> uses <font class="italic">predicate</font> to determine
whether the value of the variable is of the correct type.  If it is not,
<font class="lisp">check-arg</font> signals the <font class="lisp">:wrong-type-argument</font> condition, with four
parameters.  First, <font class="italic">type-symbol</font> if it was supplied, or else <font class="italic">predicate</font>
if it was atomic, or else <font class="lisp">nil</font>.  Second, the bad value.
Third, the name of the argument (<font class="italic">var-name</font>).
Fourth, a string describing the proper type (<font class="italic">description</font>).
If the error is proceeded, the variable is set to the value returned,
and <font class="lisp">check-arg</font> starts over, checking the type again.
Note that only the first two of these parameters are defined for
the <font class="lisp">:wrong-type-argument</font> condition, and so <font class="lisp">:wrong-type-argument</font>
handlers should only depend on the meaning of these two.
</div>

.subsection Standard Condition Names

	Some condition names are used by the kernel Lisp system, and are
documented below; since they are of global interest, they are on
the keyword package.  Programs outside the kernel system are free
to define their own condition names; it is intended that the
description of a function include a description of any conditions
that it may signal, so that people writing programs that call
that function may handle the condition if they desire.  When you
decide what package your condition names should be in, you should
apply the same criteria you would apply for determining which package
a function name should be in; if a program
defines its own condition names, they should <font class="italic">not</font> be on the
keyword package. For example, the condition names <font class="lisp">chaos:bad-packet-format</font>
and <font class="lisp">arpa:bad-packet-format</font> should be distinct.  For further
discussion, see (package).

	The following table lists all standard conditions and the
parameters they take; more will be added in the future.
These are all error-conditions, so in addition to the condition name
and the parameters, the handler receives the other arguments described above.

.table 3

.item :wrong-type-argument <font class="italic">type-name</font> <font class="italic">value</font>
<font class="italic">value</font> is the offending argument, and <font class="italic">type-name</font> is
a symbol for what type is required.  Often, <font class="italic">type-name</font>
is a predicate which returns non-<font class="lisp">nil</font> if applied to an acceptable value.
If the error is proceeded, the value returned by the handler
should be a new value for the argument to be used instead of
the one which was of the wrong type.

.item :inconsistent-arguments <font class="italic">list-of-inconsistent-argument-values</font>
These arguments were inconsistent with each other, but the fault
does not belong to any particular one of them.
This is a catch-all, and it would be good to identify subcases
in which a more specific categorization can be made.
If the error is proceeded, the value returned by the
handler will be returned by the function whose arguments were inconsistent.

.item :wrong-number-of-arguments <font class="italic">function</font> <font class="italic">number-of-args-supplied</font> <font class="italic">list-of-args-supplied</font>
<font class="italic">function</font> was invoked with the wrong number of arguments.
The elements of <font class="italic">list-of-args-supplied</font> have already been evaluated.
If the error is proceeded, the value returned should be
a value to be returned by <font class="italic">function</font>.

.item :invalid-function <font class="italic">function-name</font>
The name had a function definition but it was no good for calling.
You can proceed, supplying a value to return as the value of the
call to the function.

.item :invalid-form <font class="italic">form</font>
The so-called <font class="italic">form</font> was not a meaningful form for <font class="lisp">eval</font>.
Probably it was of a bad data type.
If the error is proceeded, the value returned
should be a new form; <font class="lisp">eval</font> will use it instead.

.item :undefined-function <font class="italic">function-name</font>
The symbol <font class="italic">function-name</font> was not defined as a function.
If the error is proceeded, then the symbol will be
defined to the function returned, and that function will be
used to continue execution.

.item :unbound-variable <font class="italic">variable-name</font>
The symbol <font class="italic">variable-name</font> had no value.
If the error is proceeded, then the symbol will be set to the value returned 
by the handler, and that value will be used to continue execution.

<!-- It's a crock that the above two clobber the original symbol.  Will be fixed some day. -->

.end_table

Currently, errors detected by microcode do not signal conditions.
Generally this means that errors in interpreted code signal conditions
and some errors in compiled code do not.  This will be corrected some
time in the future.

.subsection "Errset"

As in Maclisp, there is an <font class="italic">errset</font> facility which allows a very simple
form of error handling.  If an error occurs inside an errset, and no condition
handler handles it, i.e. the debugger would be entered, control is
returned (<font class="italic">thrown</font>) to the errset.  The errset can control whether or
not the debugger's error message is printed.

	A problem with <font class="lisp">errset</font> is that it is <font class="italic">too</font> powerful;
it will apply to any unhandled error at all.  If you are writing code
that anticipates some specific error, you should find out what condition
that error signals and set up a handler.  If you use <font class="lisp">errset</font> and
some unanticipated error crops up, you may not be told--this can cause
very strange bugs.

<div class="defspec"><font class='exdent'><font class='funcname'>errset</font><font class="italic"> Special Form</font></font><br>
The special form <font class="lisp">(errset <font class="italic">form</font> <font class="italic">flag</font>)</font> catches errors during
the evaluation of <font class="italic">form</font>.  If an error occurs, the usual error message
is printed unless <font class="italic">flag</font> is <font class="lisp">nil</font>; then, control is thrown and the errset-form
returns <font class="lisp">nil</font>.  <font class="italic">flag</font> is evaluated first and is optional, defaulting to <font class="lisp">t</font>.
If no error occurs, the value of the errset-form is a list of one element,
the value of <font class="italic">form</font>.
</div>

.defvar errset
If this variable is non-<font class="lisp">nil</font>, errset-forms are not allowed to trap errors.
The debugger is entered just as if there was no errset.  This is intended mainly
for debugging errsets.  The initial value of <font class="lisp">errset</font> is <font class="lisp">nil</font>.
.end_defvar

<div class="defspec"><font class='exdent'><font class='funcname'>err</font><font class="italic"> Special Form</font></font><br>
This is for Maclisp compatibility.

<font class="lisp">(err)</font> is a dumb way to cause an error.  If executed inside an errset,
that errset returns <font class="lisp">nil</font>, and no message is printed.
Otherwise an unseen throw-tag error occurs.

<font class="lisp">(err <font class="italic">form</font>)</font> evaluates <font class="italic">form</font> and causes the containing errset
to return the result.  If executed when not inside an errset, an unseen throw-tag error occurs.

<font class="lisp">(err <font class="italic">form</font> <font class="italic">flag</font>)</font>, which exists in Maclisp, is not supported.
</div>

<div class='section'>4.2 </div><p class='cindent'><!-- debugger -->

	When an error condition is signalled and no handlers decide to
handle the error, an interactive debugger is entered to allow the user to
look around and see what went wrong, and to help him continue the program
or abort it.  This section describes how to use the debugger.

	The user interface described herein is not thought too well of,
and we hope to redesign it sometime soon.

.subsection Entering the Debugger

	There are two kinds of errors; those generated by the Lisp Machine's
microcode, and those generated by Lisp programs (by using <font class="lisp">ferror</font> or
related functions).  When there
is a microcode error, the debugger prints out a message such as the following:
<pre class="lisp">
&gt;&gt;TRAP 5543 (TRANS-TRAP)
The symbol FOOBAR is unbound.
While in the function *EVAL  SI:LISP-TOP-LEVEL1
</pre>

	The first line of this error message indicates entry to
the debugger and contains some mysterious internal microcode information:
the micro program address, the microcode trap name and parameters, and a microcode backtrace.
Users can ignore this line in most cases.  The second line contains a description
of the error in English.  The third line indicates where the error
happened by printing a very abbreviated "backtrace" of the stack (see
below); in the example, it is saying that the error was signalled inside the
function <font class="lisp">*eval</font>, which was called by <font class="lisp">si:lisp-top-level1</font>.

	Here is an example of an error from Lisp code:

<pre class="lisp">
&gt;&gt;ERROR: The argument X was 1, which is not a symbol,
While in the function { FERROR  } FOO  *EVAL
</pre>

	Here the first line contains the English description of the
error message, and the second line contains the abbreviated backtrace.
The backtrace indicates that the function which actually entered
the error handler was <font class="lisp">ferror</font>, but that function is enclosed in
braces because it is not very important; the useful information here is
that the function <font class="lisp">foo</font> is what called <font class="lisp">ferror</font> and thus signalled
the error.

	There is not any good way to manually get into the debugger;
the interface will someday be fixed so that you can enter it at any
time if you want to use its facilities to examine the state of the Lisp
environment and so on.  In the meantime, just type an unbound symbol
at Lisp top level.

.subsection How to Use the Debugger

	Once inside the debugger, the user may give a wide variety
of commands.  This section describes how to give the commands, and then
explains them in approximate order of usefulness.  A summary is provided
at the end of the listing.

	When the error hander is waiting for a command, it prompts
with an arrow:

<pre class="lisp">

</pre>

	At this point, you may either type in a Lisp expression, or
type a command (a Control or Meta character is interpreted as a command,
whereas a normal character is interpreted as the first character of
an expression).  If you type a Lisp expression, it will be interpreted
as a Lisp form, and will be evaluated in the context of the function
which got the error.  (That is, all bindings which were in effect at
the time of the error will be in effect when your form is evaluated.)
The result of the evaluation will be printed, and the debugger
will prompt again with an arrow.  If, during the typing of the form,
you change your mind and want to get back to the debugger's
command level, type a Control-Z; the debugger will respond with
an arrow prompt.  In fact, at any time that typein is expected from
you, you may type a Control-Z to flush what you are doing and get back
to command level.  This <font class="lisp">read-eval-print</font> loop maintains the values
of <font class="lisp">+</font>, <font class="lisp">*</font>, and <font class="lisp">-</font> just as the top-level one does.

	Various debugger commands ask for Lisp objects, such as an
object to return, or the name of a catch-tag.  Whenever it tries to get
a Lisp object from you, it expects you to type in a <font class="italic">form</font>; it will
evaluate what you type in.  This provides greater generality, since
there are objects to which you might want to refer that cannot be
typed in (such as arrays).  If the form you type is non-trivial (not
just a constant form), the debugger will show you the result of
the evaluation, and ask you if it is what you intended.  It expects a Y
or N answer (see the function <font class="lisp">y-or-n-p</font>, (y-or-n-p-fun)), and if you answer negatively
it will ask you for another form.  To quit out of the command, just type
Control-Z.

.subsection "Debugger Commands"

	All debugger commands are single characters, usually with the
Control or Meta bits.  The single most useful command is Control-Z, which
exits from the debugger and throws back to the Lisp top level loop.
ITS users should note that Control-Z is not Call.
Often you are not interested in using the debugger at all and just
want to get back to Lisp top level; so you can do this in one character.
This is similar to Control-G in Maclisp.

	Self-documentation is provided by the Help (top-H) or "?" command,
which types out some documentation on the debugger commands.

	Often you want to try to continue from the error.  To do this,
use the Control-C command.  The exact way Control-C works depends on
the kind of error that happened.  For some errors, there is no standard
way to continue at all, and Control-C will just tell you this and
return to the debugger's command level.  For the very common "unbound symbol" error,
it will get a Lisp object from you, which it will store back into the
symbol.  Then it will continue as if the symbol had been bound to
that object in the first place.  For unbound-variable or undefined-function
errors, you can also just type Lisp forms to set the variable or define
the function, and then type Control-C; it will proceed without asking
anything.

	Several commands are provided to allow you to examine the
Lisp control stack (regular pdl), which keeps a record of all functions which are currently
active.  If you call <font class="lisp">foo</font> at Lisp's top level, and it calls <font class="lisp">bar</font>,
which in turn calls <font class="lisp">baz</font>, and <font class="lisp">baz</font> gets an error, then a
backtrace (a backwards trace of the stack) would show all of this
information.  The debugger has two backtrace commands.  Control-B
simply prints out the names of the functions on the stack; in the above
example it would print
<pre class="lisp">
BAZ  BAR  FOO  *SI:EVAL  SI:LISP-TOP-LEVEL1  SI:LISP-TOP-LEVEL
</pre>
The arrows indicate the direction of calling.  The Meta-B command prints
a more extensive backtrace, indicating the names of the arguments to the functions
and their current values, and also the saved address at which the function was
executing (in case you want to look at the code generated by the compiler);
for the example above it might look like:
<pre class="lisp">
FOO: (P.C. = 23)
   Arg 0 (X): 13
   Arg 1 (Y): 1

BAR: (P.C. = 120)
   Arg 0 (ADDEND): 13
</pre>
and so on.  This means that <font class="lisp">foo</font> was executing at instruction 23, and was called
with two arguments, whose names (in the Lisp source code) are <font class="lisp">x</font> and <font class="lisp">y</font>.
The current values of <font class="lisp">x</font> and <font class="lisp">y</font> are <font class="lisp">13</font> and <font class="lisp">1</font> respectively.

	The debugger knows about a "current stack frame", and there
are several commands which use it.  The initially "current" stack frame
is the one which signalled the error; either the one which got the microcode
error, or the one which called <font class="lisp">ferror</font> or <font class="lisp">error</font>.

	The command Control-L (or Form) clears the screen, retypes the
error message that was initially printed when the debugger was
entered, and then prints out a description of the current frame, in the
format used by Meta-B.  The Control-N command moves "down" to the "next" frame
(that is, it changes the current frame to be the frame which called it), and prints
out the frame in this same format.  Control-P moves "up" to the "previous" frame
(the one which this one called),
and prints out the frame in the same format.  Meta-&lt; moves to the
top of the stack, and Meta-&gt; to the bottom; both print out the new current
frame.  Control-S asks you for a string, and searches the stack for a frame
whose executing function's name contains that string.  That frame becomes current
and is printed out.  These commands are easy to remember since they are analogous
to editor commands.

	Meta-L prints out the current frame in "full screen" format, which
shows the arguments and their values, the local variables and their values,
and the machine code with an arrow pointing to the next instruction
to be executed.
Meta-N moves to the next frame and prints
it out in full-screen format, and Meta-P moves to the previous frame and
prints it out in full-screen format.  Meta-S is like Control-S but does a full-screen display.

	Control-A prints out the argument list for the function of the
current frame, as would be returned by the function <font class="lisp">arglist</font> (see (arglist-fun)).
Control-R is used to return a value from the current frame; the frame
that called that frame continues running as if the function of the current frame
had returned.  This command prompts you for a form, which it will evaluate;
it returns the resulting value, possibly after confirming it with you.
Meta-R is used to return multiple values from the current frame, but
it is not currently implemented.  The Control-T command does a <font class="italic">throw</font>
to a given tag with a given value; you are prompted for the tag and the value.

	Commands such as Control-N and meta-N, which are meaningful to repeat,
take a prefix numeric argument and repeat that many types.  The numeric argument
is typed by using Control- or Meta- and the number keys, as in the editor.

	Control-Meta-A takes a numeric argument <font class="italic">n</font>, and prints out
the value of the <font class="italic">n</font>th argument of the current frame.  It leaves <font class="lisp">*</font>
set to the value of the argument, so that you can use the Lisp <font class="lisp">read-eval-print</font>
loop to examine it.  It also leaves <font class="lisp">+</font> set to a locative pointing to the
argument on the stack, so that you can change that argument (by calling
<font class="lisp">rplaca</font> or <font class="lisp">rplacd</font> on the locative).  Control-Meta-L is similar,
but refers to the <font class="italic">n</font>th local variable of the frame.

.subsection "Summary of Commands"

.table 1
.item Control-A
Print argument list of function in current frame.
.item Control-Meta-A
Examine or change the <font class="italic">n</font>th argument of the current frame.
.item Control-B
Print brief backtrace.
.item Meta-B
Print longer backtrace.
.item Control-C
Attempt to continue.
.item Meta-C
Attempt to restart.
.item Control-G
Quit to command level.
.item Control-L
Redisplay error message and current frame.
.item Meta-L
Full-screen typeout of current frame.
.item Control-N
Move to next frame.  With argument, move down <font class="italic">n</font> frames.
.item Meta-N
Move to next frame with full-screen typeout.  With argument, move down <font class="italic">n</font> frames.
.item Control-P
Move to previous frame.  With argument, move up <font class="italic">n</font> frames.
.item Meta-P
Move to previous frame with full-screen typeout.  With argument, move up <font class="italic">n</font> frames.
.item Control-R
Return a value from the current frame.
.item Meta-R
Return several values from the current frame.  (doesn't work)
.item Control-S
Search for a frame containing a specified function.
.item Meta-S
Same as control-S but does a full display.
.item Control-T
Throw a value to a tag.
.item Control-Z
Throw back to Lisp top level.
.item ? or Help
Print a help message.
.item Meta-&lt;
Go to top of stack.
.item Meta-&gt;
Go to bottom of stack.
.item Form
Same as Control-L.
.item Line
Move to next frame.  With argument, move down <font class="italic">n</font> frames.
Same as Control-N.
.item Return
Move to previous frame.  With argument, move up <font class="italic">n</font> frames.
Same as control-P.
.end_table

.subsection "Miscellany"

	Sometimes, e.g. when the debugger is running,
microcode trapping is "disabled": any attempt by the
microcode to trap will cause the machine to halt.

<div class='defun'><font class='exdent'><font class='funcname'>trapping-enabled-p
This <font class='italic' color='purple'>predicate returns <font class="lisp">t</font> if trapping is enabled; otherwise</font></font></font><br>
it returns <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>enable-trapping <font class='italic' color='purple'>&optional (arg <font class="lisp">1</font>)</font></font></font><br>
If <font class="italic">arg</font> is <font class="lisp">1</font>, trapping is enabled.  If it is <font class="lisp">0</font>,
trapping is disabled.
</div>
.eof
</body>
</html>

